<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Berkeley DB handles</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
    <link rel="up" href="program.html" title="Chapter 15.  Programmer Notes" />
    <link rel="prev" href="program_mt.html" title="Multithreaded applications" />
    <link rel="next" href="program_namespace.html" title="Name spaces" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 11.2.5.3</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Berkeley DB handles</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="program_mt.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 15. 
		Programmer Notes
        </th>
          <td width="20%" align="right"> <a accesskey="n" href="program_namespace.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="program_scope"></a>Berkeley DB handles</h2>
          </div>
        </div>
      </div>
      <p>The Berkeley DB library has a number of object handles.  The following table
lists those handles, their scope, and whether they are free-threaded
(that is, whether multiple threads within a process can share them).</p>
      <div class="variablelist">
        <dl>
          <dt>
            <span class="term">
              <a href="../api_reference/C/env.html" class="olink">DB_ENV</a>
            </span>
          </dt>
          <dd>
            <p>
                The <a href="../api_reference/C/env.html" class="olink">DB_ENV</a> handle, created by the <a href="../api_reference/C/envcreate.html" class="olink">db_env_create()</a> method, refers
                to a Berkeley DB database environment — a collection
                of Berkeley DB subsystems, log files and databases.  <a href="../api_reference/C/env.html" class="olink">DB_ENV</a>
                handles are free-threaded if the <a href="../api_reference/C/envopen.html#envopen_DB_THREAD" class="olink">DB_THREAD</a> flag is specified
                to the <a href="../api_reference/C/envopen.html" class="olink">DB_ENV-&gt;open()</a> method when the
                environment is opened.  The handle should not be closed
                while any other handle remains open that is using it as a
                reference (for example, <a href="../api_reference/C/db.html" class="olink">DB</a>, <a href="../api_reference/C/txn.html" class="olink">TXN</a>). Once either the 
                <a href="../api_reference/C/envclose.html" class="olink">DB_ENV-&gt;close()</a> or <a href="../api_reference/C/envremove.html" class="olink">DB_ENV-&gt;remove()</a> methods
                are called, the handle may not be accessed again,
                regardless of the method's return.
            </p>
          </dd>
          <dt>
            <span class="term">
              <a href="../api_reference/C/txn.html" class="olink">TXN</a>
            </span>
          </dt>
          <dd>
            <p>
            The <a href="../api_reference/C/txn.html" class="olink">TXN</a> handle, created by the <a href="../api_reference/C/txnbegin.html" class="olink">DB_ENV-&gt;txn_begin()</a> method, refers to a
            single transaction.  The handle is not free-threaded.
            Transactions may span threads, but only serially, that is, the
            application must serialize access to the <a href="../api_reference/C/txn.html" class="olink">TXN</a> handles.  In the
            case of nested transactions, since all child transactions are
            part of the same parent transaction, they must observe the same
            constraints. That is, children may execute in different threads
            only if each child executes serially.
        </p>
            <p>
            Once the <a href="../api_reference/C/txnabort.html" class="olink">DB_TXN-&gt;abort()</a> or <a href="../api_reference/C/txncommit.html" class="olink">DB_TXN-&gt;commit()</a> methods are called, the
            handle may not be accessed again, regardless of the method's
            return.  In addition, parent transactions may not issue any
            Berkeley DB operations while they have active child
            transactions (child transactions that have not yet been
            committed or aborted) except for <a href="../api_reference/C/txnbegin.html" class="olink">DB_ENV-&gt;txn_begin()</a>, <a href="../api_reference/C/txnabort.html" class="olink">DB_TXN-&gt;abort()</a> and
            <a href="../api_reference/C/txncommit.html" class="olink">DB_TXN-&gt;commit()</a>.
        </p>
          </dd>
          <dt>
            <span class="term">
              <a href="../api_reference/C/logc.html" class="olink">DB_LOGC</a>
            </span>
          </dt>
          <dd>
            <p>
            The <a href="../api_reference/C/logc.html" class="olink">DB_LOGC</a> handle refers to a cursor into the log files.  The
            handle is not free-threaded.  Once the <a href="../api_reference/C/logcclose.html" class="olink">DB_LOGC-&gt;close()</a> method is
            called, the handle may not be accessed again, regardless of the
            method's return.
        </p>
          </dd>
          <dt>
            <span class="term">
              <a href="../api_reference/C/memp.html" class="olink">DB_MPOOLFILE</a>
            </span>
          </dt>
          <dd>
            <p>
            The <a href="../api_reference/C/memp.html" class="olink">DB_MPOOLFILE</a> handle refers to an open file in the shared memory
            buffer pool of the database environment.  The handle is not
            free-threaded.  Once the <a href="../api_reference/C/mempfclose.html" class="olink">DB_MPOOLFILE-&gt;close()</a> method is called, the
            handle may not be accessed again, regardless of the method's
            return.
        </p>
          </dd>
          <dt>
            <span class="term">
              <a href="../api_reference/C/db.html" class="olink">DB</a>
            </span>
          </dt>
          <dd>
            <p>
            The <a href="../api_reference/C/db.html" class="olink">DB</a> handle, created by the <a href="../api_reference/C/dbcreate.html" class="olink">db_create()</a> method, refers to a
            single Berkeley DB database, which may or may not be part of a
            database environment.  <a href="../api_reference/C/db.html" class="olink">DB</a> handles are free-threaded if the
            <a href="../api_reference/C/dbopen.html#open_DB_THREAD" class="olink">DB_THREAD</a> flag is specified to the <a href="../api_reference/C/dbopen.html" class="olink">DB-&gt;open()</a> method when the
            database is opened or if the database environment in which the
            database is opened is free-threaded.  The handle should not be
            closed while any other handle that refers to the database is in
            use; for example, database handles should be left open while
            cursor handles into the database remain open, or transactions
            that include operations on the database have not yet been
            committed or aborted.  Once the <a href="../api_reference/C/dbclose.html" class="olink">DB-&gt;close()</a>, <a href="../api_reference/C/dbremove.html" class="olink">DB-&gt;remove()</a> or
            <a href="../api_reference/C/dbrename.html" class="olink">DB-&gt;rename()</a> methods are called, the handle may not be accessed
            again, regardless of the method's return.
        </p>
          </dd>
          <dt>
            <span class="term">
              <a href="../api_reference/C/dbc.html" class="olink">DBC</a>
            </span>
          </dt>
          <dd>
            <p>
            The <a href="../api_reference/C/dbc.html" class="olink">DBC</a> handle refers to a cursor into a Berkeley DB
            database.  The handle is not free-threaded.  Cursors may span
            threads, but only serially, that is, the application must
            serialize access to the <a href="../api_reference/C/dbc.html" class="olink">DBC</a> handles.  If the cursor is to be
            used to perform operations on behalf of a transaction, the
            cursor must be opened and closed within the context of that
            single transaction.  Once <a href="../api_reference/C/dbcclose.html" class="olink">DBC-&gt;close()</a> has been called, the
            handle may not be accessed again, regardless of the method's
            return.
        </p>
          </dd>
        </dl>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="program_mt.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="program.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="program_namespace.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Multithreaded applications </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Name spaces</td>
        </tr>
      </table>
    </div>
  </body>
</html>
